<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Configuring the Server</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Getting Started with Distributed Berkeley DB Applications" />
    <link rel="up" href="server.html" title="Chapter 2. Berkeley DB Server" />
    <link rel="prev" href="server.ssl.html" title="Enabling SSL for the Server" />
    <link rel="next" href="utilities.html" title="Impacts on Utility Programs" />
  </head>
  <body>
    <div xmlns="" class="navheader">
      <div class="libver">
        <p>Library Version 12.1.6.2</p>
      </div>
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Configuring the Server</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="server.ssl.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 2. Berkeley DB Server</th>
          <td width="20%" align="right"> <a accesskey="n" href="utilities.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="config"></a>Configuring the Server</h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <dl>
          <dt>
            <span class="sect2">
              <a href="config.html#log4j">log4j Configuration File</a>
            </span>
          </dt>
          <dt>
            <span class="sect2">
              <a href="config.html#properties">Server Configuration File</a>
            </span>
          </dt>
        </dl>
      </div>
      <p>
            Berkeley DB server uses two configuration files, one for log4j,
            and the other for the server itself. After a change to a
            configuration file, the server must be restarted to pick up the
            change.
        </p>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="log4j"></a>log4j Configuration File</h3>
            </div>
          </div>
        </div>
        <p>
                Berkeley DB server uses log4j, and thus requires a log4j
                configuration file. Berkeley DB server accepts configuration
                files in XML only. By default, it looks for a
                <code class="literal">log4j.xml</code> file under the current working
                directory. This can be overridden by the
                <code class="literal">-log-config</code> command-line argument when
                the server is started.
            </p>
        <p>
                An example log4j configuration file for a Berkeley DB server:
            </p>
        <pre class="programlisting">&lt;?xml version="1.0" encoding="UTF-8" ?&gt;
&lt;!DOCTYPE log4j:configuration SYSTEM "log4j.dtd"&gt;

&lt;log4j:configuration xmlns:log4j="http://jakarta.apache.org/log4j/"&gt;
    &lt;appender name="File" class="org.apache.log4j.RollingFileAppender"&gt;
        &lt;param name="File" value="path-to-log-file"/&gt;
        &lt;param name="MaxBackupIndex" value="20"/&gt;
        &lt;param name="MaxFileSize" value="50MB"/&gt;
        &lt;layout class="org.apache.log4j.PatternLayout"&gt;
            &lt;param name="ConversionPattern" 
                value="%d [%t] %-5p %c - %m%n"/&gt;
        &lt;/layout&gt;
    &lt;/appender&gt;
    &lt;appender name="Async" class="org.apache.log4j.AsyncAppender"&gt;
        &lt;param name="BufferSize" value="256"/&gt;
        &lt;appender-ref ref="File" /&gt;
    &lt;/appender&gt;
    &lt;root&gt;
        &lt;level value="INFO"/&gt;
        &lt;appender-ref ref="Async"/&gt;
    &lt;/root&gt;
&lt;/log4j:configuration&gt;</pre>
      </div>
      <div class="sect2" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h3 class="title"><a id="properties"></a>Server Configuration File</h3>
            </div>
          </div>
        </div>
        <p>
                Berkeley DB server also uses a Java properties file to control
                its own behavior. By default, the server looks for a
                <code class="literal">bdb.properties</code> file under the current
                working directory. This can be overridden by the
                <code class="literal">-config-file</code> command-line argument when
                the server is started. 
            </p>
        <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
          <h3 class="title">Note</h3>
          <p> 
                    Because this file may contain sensitive information, its
                    permissions should be limited to the minimum. If the file is
                    accessible globally (globally readable, writable or
                    executable), the server would not start. 
                </p>
        </div>
        <p>
                An example configuration file for a Berkeley DB server: 
            </p>
        <pre class="programlisting">###################################
# Server configuration
###################################

# The server's listening port

port=8080

# If SSL is enabled, this indicates the maximum number of concurrent
# client connections.
#
# If SSL is disabled, there is no limit on the number of concurrent
# connections, and this parameter indicates the maximum number of
# requests that can be processed concurrently.

workers=10

# Configure the host name of this server. SSL is enabled if ssl.host
# is set.

#ssl.host=server-host-name

# Configure the key store for SSL.

#ssl.keyStore=path-to-key-store
#ssl.keyStore.password=key-store-password
#ssl.keyStore.type=jks
#ssl.keyStore.manager=SunX509

# Configure the trust store for SSL.

#ssl.trustStore=path-to-trust-store
#ssl.trustStore.password=trust-store-password
#ssl.trustStore.type=jks
#ssl.trustStore.manager=PKIX

###################################
# Database service configurations
###################################

# The root directory for all environments, the home directory for an
# environment with name "&lt;env&gt;" is $root.home/&lt;env&gt;

root.home=path-to-environment-root-directory

# The root directory for all data directories, the data directory
# for an environment with name "&lt;env&gt;" is $root.data/&lt;env&gt;

root.data=path-to-data-root-directory

# The root directory for all blob directories, the blob directory
# for an environment with name "&lt;env&gt;" is $root.blob/&lt;env&gt;

root.blob=path-to-blob-root-directory

# The root directory for all log directories, the log directory for
# an environment with name "&lt;env&gt;" is $root.log/&lt;env&gt;

root.log=path-to-db-log-root-directory

# Configure the timeout value for open handles. The timeout value
# is set in seconds.
#
# For example, if the timeout is set to 600 seconds (10 minutes),
# and a handle has not been accessed for longer than 600 seconds,
# then this handle will be closed automatically when the cleanup
# worker runs the next time.

handle.timeout=600

# The frequency the cleanup worker runs. The frequency is set in
# seconds.
#
# For example, if the frequency is set to 300 seconds, the
# cleanup worker runs every 300 seconds.

cleanup.interval=300</pre>
        <div class="sect3" lang="en" xml:lang="en">
          <div class="titlepage">
            <div>
              <div>
                <h4 class="title"><a id="server_conf"></a>Server Configuration Options</h4>
              </div>
            </div>
          </div>
          <p>
                    The server can be configured with the following options:
                </p>
          <div class="itemizedlist">
            <ul type="disc">
              <li>
                <p><a id="server_conf.port"></a>
                            <span class="bold"><strong>port</strong></span>
                        </p>
                <p> 
                            Specifies the port number the server listens for
                            client connections. The default value is 8080.
                        </p>
              </li>
              <li>
                <p><a id="server_conf.workers"></a>
                            <span class="bold"><strong>workers</strong></span>
                        </p>
                <p> 
                            Specifies the number of worker threads used for
                            handling client requests. The default value is 20.
                        </p>
                <p> 
                            If SSL is not enabled, client requests are
                            handled by a shared pool of worker threads. A free
                            worker thread is chosen to handle each client
                            request, and the worker thread becomes free again
                            after handling the request. The number of worker
                            threads determines the maximum number of client
                            requests that can be handled concurrently. If the
                            number of concurrent requests exceeds the number of
                            worker threads, later requests will be blocked until
                            a free worker thread is available.
                            </p>
                <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
                  <h3 class="title">Note</h3>
                  <p> 
                                   In this mode, the number of concurrent
                                   client connections is limited only by system
                                   resources. For example, the server can serve
                                   200 concurrent client connections even if
                                   the <span class="emphasis"><em>workers</em></span> is set to
                                   20. 
                                </p>
                </div>
                <p>
                        </p>
                <p> 
                            If SSL is enabled, each client is handled by a
                            dedicated worker thread. Therefore, the number of
                            worker threads determines the maximum number of
                            concurrent client connections. For example, if
                            <span class="emphasis"><em>workers</em></span> is set to 100, the
                            server can serve a maximum of 100 concurrent client
                            connections. If more clients try to connect to the
                            server, they are blocked until some client
                            disconnects from the server or the connection times
                            out (the timeout is specified by the user). 
                        </p>
              </li>
              <li>
                <p><a id="server_conf.ssl.host"></a>
                            <span class="bold"><strong>ssl.host</strong></span>
                        </p>
                <p>
                            SSL is enabled if this property is specified.
                            This property specifies the host name of the server.
                            Clients should use this name when connecting to the
                            server. There is no default value, and SSL is
                            disabled by default.
                        </p>
              </li>
              <li>
                <p><a id="server_conf.ssl.keyStore"></a>
                            <span class="bold"><strong>ssl.keyStore</strong></span>
                        </p>
                <p> 
                            Specifies the path to the Java key store file
                            which manages the server's private key. There is no
                            default value. 
                        </p>
                <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
                  <h3 class="title">Note</h3>
                  <p>
                               This file maintains sensitive information. If
                               the file is accessible globally (globally
                               readable, writable or executable), the server
                               would not start. 
                            </p>
                </div>
              </li>
              <li>
                <p><a id="server_conf.ssl.keyStore.password"></a>
                            <span class="bold"><strong>ssl.keyStore.password</strong></span>
                        </p>
                <p> 
                            Specifies the password of the key store file
                            specified in <span class="emphasis"><em>ssl.keyStore</em></span>.
                            There is no default value. 
                        </p>
              </li>
              <li>
                <p><a id="server_conf.ssl.keyStore.type"></a>
                            <span class="bold"><strong>ssl.keyStore.type</strong></span>
                        </p>
                <p> 
                            Specifies the type of the key store file
                            specified in <span class="emphasis"><em>ssl.keyStore</em></span>.
                            There is no default value. 
                        </p>
              </li>
              <li>
                <p><a id="server_conf.ssl.keyStore.manager"></a>
                            <span class="bold"><strong>ssl.keyStore.manager</strong></span>
                        </p>
                <p>
                            Specifies the algorithm name of the key manager
                            factory. There is no default value. 
                        </p>
              </li>
              <li>
                <p><a id="server_conf.ssl.trustStore"></a>
                            <span class="bold"><strong>ssl.trustStore</strong></span>
                        </p>
                <p> 
                            Specifies the path to the Java trust store file
                            which manages the server's trusted public
                            certificates. There is no default value.
                        </p>
                <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
                  <h3 class="title">Note</h3>
                  <p> 
                               This file maintains sensitive information. If
                               the file is accessible globally (globally
                               readable, writable or executable), the server
                               would not start.
                            </p>
                </div>
              </li>
              <li>
                <p><a id="server_conf.ssl.trustStore.password"></a>
                            <span class="bold"><strong>ssl.trustStore.password</strong></span>
                        </p>
                <p>
                            Specifies the password of the trust store file
                            specified in <span class="emphasis"><em>ssl.trustStore</em></span>.
                            There is no default value. 
                        </p>
              </li>
              <li>
                <p><a id="server_conf.ssl.trustStore.type"></a>
                            <span class="bold"><strong>ssl.trustStore.type</strong></span>
                        </p>
                <p> 
                            Specifies the type of the trust store file
                            specified in <span class="emphasis"><em>ssl.trustStore</em></span>.
                            There is no default value.
                        </p>
              </li>
              <li>
                <p><a id="server_conf.ssl.trustStore.manager"></a>
                            <span class="bold"><strong>ssl.trustStore.manager</strong></span>
                        </p>
                <p> 
                            Specifies the algorithm name of the trust manager
                            factory. There is no default value. 
                        </p>
              </li>
              <li>
                <p><a id="server_conf.root.home"></a>
                            <span class="bold"><strong>root.home</strong></span>
                        </p>
                <p>
                            The root directory for all environment's home
                            directory. For example, if the environment home
                            specified by a client is
                            <span class="emphasis"><em>env_home</em></span>, the actual home
                            directory on the server is
                            <span class="emphasis"><em>&lt;root.home&gt;/env_home</em></span>.
                            The default value is the current working directory. 
                        </p>
                <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;">
                  <h3 class="title">Note</h3>
                  <p>
                               The environment home specified by a client
                               cannot escape the specified root directory.
                               Absolute paths or relative paths that escape the
                               root directory are not allowed. 
                            </p>
                </div>
              </li>
              <li>
                <p><a id="server_conf.root.data"></a>
                            <span class="bold"><strong>root.data</strong></span>
                        </p>
                <p>
                            The root directory for all environment's data
                            directories. For example, if the environment home
                            specified by a client is
                            <span class="emphasis"><em>env_home</em></span>, the actual
                            directory for access method database files of this
                            environment is
                            <span class="emphasis"><em>&lt;root.data&gt;/env_home</em></span>. 
                        </p>
                <p> 
                            If this property is not specified,
                            <span class="emphasis"><em>root.home</em></span> is used. 
                        </p>
              </li>
              <li>
                <p><a id="server_conf.root.blob"></a>
                            <span class="bold"><strong>root.blob</strong></span>
                        </p>
                <p> 
                            The root directory for all environment's blob
                            directories. For example, if the environment home
                            specified by a client is
                            <span class="emphasis"><em>env_home</em></span>, the actual
                            directory for blob files of this environment is
                            <span class="emphasis"><em>&lt;root.blob&gt;/env_home</em></span>. 
                        </p>
                <p> 
                            If this property is not specified,
                            <span class="emphasis"><em>root.home</em></span> is used. 
                        </p>
              </li>
              <li>
                <p><a id="server_conf.root.log"></a>
                            <span class="bold"><strong>root.log</strong></span>
                        </p>
                <p> 
                            The root directory for all environment's log
                            directories. For example, if the environment home
                            specified by a client is
                            <span class="emphasis"><em>env_home</em></span>, the actual
                            directory for log files of this environment is
                            <span class="emphasis"><em>&lt;root.log&gt;/env_home</em></span>. 
                        </p>
                <p> 
                            If this property is not specified,
                            <span class="emphasis"><em>root.home</em></span> is used. 
                        </p>
              </li>
              <li>
                <p><a id="server_conf.handle.timeout"></a>
                            <span class="bold"><a id="server_conf.handle.timeout.title"></a><strong>handle.timeout</strong></span>
                        </p>
                <p> 
                            Specifies the timeout for open handles on the
                            server, in seconds. The server scans all open
                            handles periodically, and closes those handles that
                            have not been accessed for the last
                            <span class="emphasis"><em>handle.timeout</em></span> seconds. The
                            default value is 600. 
                        </p>
              </li>
              <li>
                <p><a id="server_conf.cleanup.interval"></a>
                            <span class="bold"><a id="server_conf.cleanup.interval.title"></a><strong>cleanup.interval</strong></span>
                        </p>
                <p> 
                            Specifies the interval between consecutive scans
                            of open handles, in seconds. The default value is
                            300. 
                        </p>
              </li>
            </ul>
          </div>
        </div>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="server.ssl.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="server.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="utilities.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Enabling SSL for the Server </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Impacts on Utility Programs</td>
        </tr>
      </table>
    </div>
  </body>
</html>
